cs-arl-xapi

Esta sección describe los atributos y uso detallado del Servicio API Experience ARL (Administradora de Riesgos Laborales).

💂️ Información Base

• Título de la API: Servicio API Experience ARL
• Versión: v1
• URL Base: https://cs-arl-xapi-v1-{env}.us-e1.cloudhub.io/api/

Reemplaza {env} con:
- dev (Desarrollo)
- qa (Aseguramiento de Calidad)
- prod (Producción - pendiente de configuración)

🔑 Autenticación

Encabezados Requeridos

• Authorization

  • Longitud: 36 - 500 caracteres
  • Ejemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• client_id

  • Longitud: 32 - 36 caracteres
  • Ejemplo: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

• invoker (Opcional pero recomendado)

  • Formato: JSON string
  • Ejemplo: {"application":"Portal","addressIPUser":"192.168.1.10","loginUser":"admin","userName":"Admin User"}

📌 Los encabezados Authorization y client_id son obligatorios en todas las solicitudes. El header invoker es opcional pero altamente recomendado para trazabilidad.

✨ Endpoint: Crear Trabajador Dependiente

POST /create-dependent-worker

• Descripción: Registra un nuevo trabajador dependiente en el sistema ARL con toda su información laboral, personal y contractual.

Cuerpo de Solicitud

{
  "afp": {
    "id": "string (requerido)",
    "name": "string (requerido)"
  },
  "previousArp": {
    "id": "string (opcional)",
    "name": "string (opcional)"
  },
  "position": "string (requerido, máx 100)",
  "city": {
    "id": "string (requerido, 5 dígitos)",
    "name": "string (requerido)"
  },
  "contractId": "string (requerido)",
  "headquarterId": "string (requerido)",
  "workerId": "string (requerido)",
  "email": "string (opcional, formato email)",
  "department": {
    "id": "string (requerido, 2 dígitos)",
    "name": "string (requerido)"
  },
  "address": "string (requerido, máx 200)",
  "eps": {
    "id": "string (requerido)",
    "name": "string (requerido)"
  },
  "fax": "string (opcional)",
  "endEffectiveDate": "datetime (requerido, ISO 8601)",
  "admissionDate": "datetime (requerido, ISO 8601)",
  "initEffectiveDate": "datetime (requerido, ISO 8601)",
  "birthdate": "datetime (requerido, ISO 8601)",
  "teleworkerSchedules": [
    {
      "day": "string (requerido)",
      "hour01": "boolean (requerido)",
      "hour02": "boolean (requerido)",
      "...": "boolean (hasta hour24)"
    }
  ],
  "workday": {
    "id": "string (requerido)",
    "name": "string (requerido)"
  },
  "workingDay": {
    "id": "string (requerido)",
    "name": "string (requerido)"
  },
  "communeLocation": "string (opcional)",
  "identification": "string (requerido, 6-15 dígitos)",
  "usualOccupation": {
    "id": "string (requerido)",
    "name": "string (requerido)"
  },
  "firstSurname": "string (requerido, máx 50)",
  "firstname": "string (requerido, máx 50)",
  "basicSalary": "string (requerido, formato decimal)",
  "secondSurname": "string (opcional, máx 50)",
  "secondName": "string (opcional, máx 50)",
  "gender": {
    "id": "string (requerido, M/F)",
    "name": "string (requerido)"
  },
  "subContributorType": {
    "id": "string (opcional)",
    "name": "string (opcional)"
  },
  "cellphone": "string (opcional, 10 dígitos)",
  "phone": "string (opcional, 7-10 dígitos)",
  "usualOccupationTime": "string (opcional)",
  "contractType": {
    "id": "string (requerido)",
    "name": "string (requerido)"
  },
  "contributorType": {
    "id": "string (requerido)",
    "name": "string (requerido)"
  },
  "identificationType": {
    "id": "string (requerido, ej: CC, TI, CE, PA)",
    "name": "string (requerido)"
  }
}

Cuerpo de Respuesta

{
  "initEffectiveDate": "datetime",
  "filingNewDate": "datetime",
  "identification": "string",
  "filingNumber": "string",
  "firstSurname": "string",
  "firstname": "string",
  "secondSurname": "string",
  "secondName": "string",
  "identificationType": {
    "id": "string",
    "name": "string"
  },
  "noveltyType": {
    "id": "string",
    "name": "string"
  },
  "hash": "string (SHA256)"
}

📋 Endpoint: Consultar Trabajadores Retirados

POST /retired-dependent-workers-cancelled

• Descripción: Obtiene un reporte en PDF (codificado en Base64) de trabajadores dependientes retirados o cancelados.

Cuerpo de Solicitud

{
  "contractId": "string (requerido)",
  "workerId": "string (requerido)",
  "cityCode": "string (requerido, 5 dígitos, ej: 11001)",
  "consecutive": "string (requerido)",
  "consecutiveContract": "integer (requerido)",
  "consecutiveHeadquarters": "integer (requerido)",
  "workerState": "string (requerido, valores: R=Retirado, C=Cancelado)",
  "dateStartEffect": "string (requerido, formato: YYYYMMDD)",
  "dateEndValidity": "string (requerido, formato: YYYYMMDD)",
  "quoteType": "string (requerido)",
  "employeeType": "string (requerido, ej: Dependiente, Independiente)",
  "reportType": "string (requerido, valores: PDF, CSV)",
  "workerIdentification": [
    {
      "numberIdentification": "string (requerido, 6-15 dígitos)",
      "typeIdentification": "string (requerido, ej: CC, TI, CE)"
    }
  ]
}

Cuerpo de Respuesta

{
  "report": "string (Base64 encoded PDF)",
  "hash": "string (SHA256 hash de seguridad)"
}

Nota sobre el hash: El hash se genera mediante SHA256 con la fórmula: idContrato+idTrabajador+tipoTransaccion(C/R)+fechaTransacción

🏢 Endpoint: Consultar Datos de Trabajadores Dependientes

GET /workers/dependent/data

• Descripción: Consulta datos completos de trabajadores dependientes activos en el sistema.

Parámetros de Consulta

Cuerpo de Respuesta

Retorna un objeto con información completa del trabajador incluyendo datos personales, laborales y contractuales.

🏭 Endpoint: Consultar Sedes Empresariales

GET /companies/headquarters/{contractConsecutive}

• Descripción: Obtiene información de las sedes de una empresa basándose en el consecutivo del contrato.

Parámetros de Ruta

Cuerpo de Respuesta

Retorna un arreglo con información de las sedes incluyendo dirección, ciudad, departamento y datos de contacto.

🌍 Endpoint: Consultar Departamentos

GET /obtain-departments

• Descripción: Lista todos los departamentos disponibles en el sistema para Colombia.

Parámetros de Consulta

No requiere parámetros.

Cuerpo de Respuesta

[
  {
    "id": "string (código departamento)",
    "name": "string (nombre departamento)"
  }
]

🏙️ Endpoint: Consultar Ciudades

GET /cities

• Descripción: Consulta ciudades disponibles, opcionalmente filtradas por departamento.

Parámetros de Consulta

Cuerpo de Respuesta

[
  {
    "id": "string (código ciudad, 5 dígitos)",
    "name": "string (nombre ciudad)",
    "departmentId": "string (código departamento)"
  }
]

🏥 Endpoint: Consultar Ubicación de IPS

GET /ips-location

• Descripción: Obtiene ubicación geográfica de IPS (Instituciones Prestadoras de Salud).

Parámetros de Consulta

Cuerpo de Respuesta

Retorna un arreglo con información de IPS incluyendo nombre, dirección, ciudad, departamento, teléfonos y coordenadas geográficas.

💊 Endpoint: Crear Autorización Médica

POST /authorization/medical-authorizations

• Descripción: Crea una autorización médica para trabajadores con validaciones de cobertura ARL.

Cuerpo de Solicitud

{
  "workerIdentification": "string (requerido)",
  "identificationType": "string (requerido)",
  "authorizationType": "string (requerido)",
  "diagnosis": "string (requerido, código CIE-10)",
  "ipsCode": "string (requerido)",
  "treatmentDescription": "string (requerido)",
  "authorizationDate": "datetime (requerido, ISO 8601)",
  "validityDays": "integer (requerido, rango: 1-365)"
}

Cuerpo de Respuesta

Retorna un objeto con el número de autorización, estado, vigencia y detalles del servicio autorizado.

📝 Resumen de Endpoints

📎 Consulta los archivos de ejemplo asociados para esquemas detallados:
- src/main/resources/api/examples/requests/
- src/main/resources/api/examples/responses/

📊 Parámetros Comunes

🔐 Esquemas de Seguridad

Aplicación de Client ID

OAuth 2.0

Header Invoker (Opcional)

🗂️ Tipos de Identificación Soportados

📅 Formatos de Fecha

ISO 8601 (DateTime)

• Formato: YYYY-MM-DDTHH:mm:ss
• Ejemplo: 2024-11-13T10:30:00

Formato Comprimido (String)

• Formato: YYYYMMDD
• Ejemplo: 20241113

⚠️ Códigos de Error

🔍 Estructura de Errores

Respuesta de Error Estándar

{
  "code": 400,
  "message": "Descripción detallada del error",
  "transactionId": "UUID del correlationId"
}

Ejemplo de Error de Validación

{
  "code": 400,
  "message": "Bad request: Missing required field 'identification'",
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

📞 Soporte

Para asistencia técnica, contacta al equipo de Coordinación de Servicios de Integración y Aplicaciones.

Correo electrónico: epalma@fgs.co

📅 Información Adicional

Documentación técnica creada y actualizada en Noviembre 2025 por epalma@fgs.co - Edna Nayibe Palma

© 2025 Fundación Grupo Social - Colmena. Archivo generado para la API cs-arl-xapi

📋 Nota Importante: Esta documentación se actualiza continuamente. Para la versión más reciente y cambios en tiempo real, consulta siempre el Portal de Exchange oficial.

🔒 Aviso de Seguridad: Nunca compartas credenciales de API en repositorios públicos o documentación. Usa siempre variables de entorno para información sensible y rota tokens regularmente.

⚡ Límites de Rate: Esta API tiene un límite de 100 requests por minuto por client_id. Para necesidades mayores, contacta al equipo de soporte.

🔄 Correlation ID: Todas las transacciones generan automáticamente un correlationId único para trazabilidad. Conserva este ID para reportar incidencias.